﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="AtomApi.cs" company="Marek Dzikiewicz">
//   Marek Dzikiewicz, All Rights Reserved.
// </copyright>
// --------------------------------------------------------------------------------------------------------------------

namespace Dzikiewicz.WinApi.Kernel.Data
{
    using System.Runtime.InteropServices;

    /// <summary>
    /// Exposes WinAPI functions for Atom table management.
    /// </summary>
    public static class AtomApi
    {
        /// <summary>
        /// Adds a character string to the global atom table and returns a unique value (an atom) identifying the 
        /// string.
        /// </summary>
        /// <param name="str">
        /// The null-terminated string to be added. The string can have a maximum size of 255 bytes. Strings that 
        /// differ only in case are considered identical. The case of the first string of this name added to the table 
        /// is preserved and returned by the GlobalGetAtomName function. Alternatively, you can use an integer atom 
        /// that has been converted using the MAKEINTATOM macro. See the Remarks for more information.
        /// </param>
        /// <returns>
        /// If the function succeeds, the return value is the newly created atom. If the function fails, the return 
        /// value is zero. To get extended error information, call <c>GetLastError</c>.
        /// </returns>
        [DllImport("kernel32", SetLastError = true)]
        public static extern short GlobalAddAtom(string str);

        /// <summary>
        /// Decrements the reference count of a global string atom. If the atom's reference count reaches zero, 
        /// <see cref="GlobalDeleteAtom"/> removes the string associated with the atom from the global atom table.
        /// </summary>
        /// <param name="atom">The atom and character string to be deleted.</param>
        /// <returns>The function always returns 0.</returns>
        [DllImport("kernel32", SetLastError = true)]
        public static extern short GlobalDeleteAtom(short atom);
    }
}